Method Euphoria 3.0.0

© October2010 by Michael A. Nelson

mikestar13@sbcglobal.net

 

TABLE OF CONTENTS

 

WHAT IS METHOD EUPHORIA?

Method Euphoria is a library written in the Euphoria programming language (version 2.5). It is intended to allow programmers to use object-oriented programming in Euphoria, by allowing the definition of classes, and the creation and use of objects based on these classes.

Method Euphoria was designed to be powerful and secure, even at the cost of complexity. Method Euphoria is intended for the advanced OOP programmer.

Method Euphoria is built around the idea that methods are the foundation of OOP programming: properties and events are implemented via methods.

 

FEATURES OF METHOD EUPHORIA

 

OBJECT ORIENTED PROGRAMMING IN METHOD EUPHORIA

The fundamental concept of object-oriented programming (OOP) is the object. An object may be thought of as a semi-independent program containing data (properties) and routines (methods). An object represents an entity: a truck, a checking account, a character in a role-playing game, etc. Properties represent attributes of these entities: a truck's weight limit, a checking account's balance, a character's experience points. Methods represent actions performed by or on the entity: a truck turns, a check is debited to a checking account, and a character attacks a monster. One common way of expressing this it an object consists of its state (properties) and its behavior (methods).

Method Euphoria also supports events. Events are a specialized form of methods.

Because object is a Euphoria data type, from here on an object in the OOP sense above will be called an entity.

Classes are types of entities: trucks, checking accounts, characters. Classes are blueprints for the creation of entities. Classes may also have properties and methods: attributes and actions pertaining to the whole class rather than to a particular entity. The simplest example would be a class property used as a counter to determine the number of entities of that class which have been created.

In Method Euphoria, classes are also entities (see Entities).

A class may be derived from another class and inherit properties and methods from that class. The class derived from is called a superclass; the derived class is called a subclass. For example, if there is a class Car, you could define Police_Car as a subclass of Car, inheriting all the properties and methods of Car and adding new properties and methods to represent attributes and actions of police cars which do not apply to normal cars.

Inherited methods may be redefined by a subclass; inherited properties may not be redefined as such, but their accessor methods may be redefined.

In OOP terminology, the kind of redefinition above is called overriding. Method Euphoria does not support method overloading, which refers to defining more than one method with the same name in a class, but with a different number of parameters or different parameter types.

 

PROGRAM CONTEXT

Method Euphoria defines three program contexts—initialization, class definition, and method. A Method Euphoria program begins in initialization, where classes may be defined. Class definition context means a class definition is in progress. The program returns to initialization context when a class definition is completed. When all class definitions are complete, the program will call the procedure main_program. This takes a class as its parameter and calls that class’ main method. (Alternatively, start_program can be used.) The program will remain in method context until program termination.

Many Method Euphoria routines can only be used in certain program contexts. Also, some Method Euphoria routines are not allowed if an exception is pending. For information on specific routines, see the alphabetical listing.

 

POLYMORPHISM

There are various definitions of polymorphism. The definition used in Method Euphoria is as follows: Assume Alpha is a class and Beta is a subclass of Alpha. Whenever an Alpha instance or the Alpha class may be used, a Beta instance or the Beta class may be used in its place. The definition is not reversible: it may be possible to use an Alpha instance or the Alpha class in place of a Beta instance or the Beta class, but this is not required.

As a logical consequence of this definition, if Beta overrides an Alpha method, the Beta method must not have more restrictive access than the overridden Alpha method.

 

ENTITIES

An entity consists of two parts--a handle and a value. The handle is a reference with which the value may be manipulated by Method Euphoria. Internally, a handle is a three-integer sequence. The first element is the Euphoria's largest negative integer, the second indicates the location in the local sequence in which Method Euphoria maintains the values of all instance entities (or 0 if the entity is a class), and the third indicates the class. The chance of normal data reproducing this by chance is virtually zero, so if entity(x) returns TRUE, x is an entity. However, sequence(x) will of course also return TRUE.

Because an entity is a reference, x=y where x and y are entities results in only the handle being copied, x and y share the same internal data and a change in one will result in a change in the other. To make an actual copy of an entity, use the entity's clone method.

Method Euphoria defines three types of entities—instance, class, and deleted:

An instance entity is a particular entity belonging to a class. This is the typical object in Object Oriented Programming.

For classes, see below.

A deleted entity is an instance which no longer contains data due to having been deleted. For type checking purposes, a deleted entity is not treated as an entity.

 

CLASSES

A class is an entity which is used as a blueprint for creating instances. There are three types of classes:

  1. Normal classes: Method Euphoria provides a universal base class named Entity with special methods inherited by every normal class. Entity has no superclass; normal classes must have exactly one superclass.
  2. Interfaces: Method Euphoria provides a universal base class named Interface which is the superclass of all interfaces. Interface has no superclass; interfaces may have one or more superclasses. (See Interfaces.)
  3. Exceptions: Method Euphoria provides a universal base class named Exception which is the superclass of all exceptions. Exception has no superclass; exceptions must have exactly one superclass. (See Exceptions and Exception Handling.)

 

PACKAGES

It is essential that all classes used in a program must be distinguishable from each other. A class is identified by its handle and by its name. It is no problem if classes from different sources might have the same name for their handle constants: Euphoria namespacing will resolve the issue. But for saving and restoring entities, handles cannot be used as they are dependent on the particular program and often a particular run of that program. For saving and restoring entities, the class name is used. It is entirely likely that class names will be duplicated. In order to resolve these ambiguities, Method Euphoria implements a package concept. Classes are grouped into packages and Method Euphoria will allow two classes with the same name to be used in a program if and only if the two classes belong to different packages. The package procedure defines a package; any class defined from the point that package is encountered until an end_ package procedure is encountered are part of that package. Packages may be nested. If a class is defined before any package procedure is encountered, it will not belong to any package (this can be interpreted as belonging to an anonymous default package).

Whenever a class is used, its name expressed as a string may be used in place of its handle constant. This will allow the solution of some namespace problems. The fully qualifed class name (for example "ME_Std_Lib.Containers.Map") will always work. The class name alone is sufficient:

  1. In class, interface, or exception where the class is in the same package as the class being defined.
  2. In all cases during the execution of a method, if the class is in the same package as the class which defined the method currently being executed.
  3. If the class is in the ME_Kernel or ME_Std_Lib packages, unless this results in a name clash with case 1 or 2.

 

ACCESS RIGHTS

Access rights control access to methods of a class. The three types of access are:

  1. PUBLIC: the method may be called by a method of any class.
  2. PROTECTED: the method may be called by a method of the class which defines the method or a superclass of that class. A method of a subclass of the defining class may call the method if the target belongs to the subclass or of one of the subclass's subclasses, but may not call the method otherwise.
  3. PRIVATE: the method may be called by a method of the class which defines the method or a superclass of that class.

Suppose we have four classes A, B, C, and D where B is a subclass of A, C is a subclass of B and D is a subclass of C. Class B defines three instance methods: x with public access, y with protected access, and z with private access. An unrelated class' method may call only method x. A class A or class B method can call all three methods. A class C method can call x, and can call the y method with an instance of class C or D as its target, but cannot call the y method with an instance of B as its target. A class D method can call x and can call the y method with an instance of D as its target, but cannot call the y method with an instance of B or C as its target.

 

PROPERTIES

Properties represent the state of an entity. In Method Euphoria, properties can only be accessed by methods defined by the class which defines the property. Properties are inherited from superclasses, but overriding is not allowed. If less restrictive access is needed, accessor methods must be defined. Normally, there are two accessor methods per property, a getter to read the property and a setter to write it. The property procedure can cause accessor methods to be generated for you automatically. See also get_property and set_property.

 

METHODS

Methods represent the behavior of an entity. Methods are inherited from superclasses and can be overridden. The universal base class Entity provides some special methods. See method and call_method.

 

METHOD OVERRIDING

Methods inherited from a superclass can be overridden. To override a method, define an instance method or a class method (as the case may be) with the same name in the subclass. The overriding method must have the same access rights or less restrictive access rights than the overridden method. Thus a private method may be overridden by a public method, but a public method may not be overridden by a private method. Sometimes the whole purpose of overriding is to use less restrictive access. An overridden method can be called by using call_super in the overriding method.

Overriding is the mechanism which makes polymorphism work. For example: A is a class and B is a subclass of A. A defines an instance method x and B overrides x with its own method. Then call_method(z,"x",{15}) will call A's method x if z is an instance of A, but will call B's method x if z is an instance of B.

 

SPECIAL METHODS

The universal base class Entity provides three special methods which are inherited by every class:

  1. Class method new: this method creates a new instance entity of the calling class.
  2. Instance method clone: this method creates a shallow copy of its target instance. In a shallow copy, if a property of the instance is also an instance, only the reference is copied. If a deep copy (properties which are instances are cloned) is needed for instances of a given class, that class can override the clone method.
  3. Instance method delete: this method destroys its target instance. The delete method reclaims memory used by an instance which is no longer needed. A class may override the delete method to release resources such as file or window handles used by the instance, or to delete instances which are contained in the instance.

These methods are protected in Entity. Usually you will want to override new and delete in your class to make them public. If you want to be able to copy instances of your class, override clone to make it public.

There are cases where you may want to leave these methods protected to control the creation, destruction, or copying of your class's instances.

 

AUTOMATIC METHOD CALLS

Method Euphoria calls certain methods automatically without the use of call_method. Automatic calls ignore access rights. This only applies to the direct call--any method calls by the called method work normally. Method Euphoria makes the following automatic method calls:

  1. main_program and start_program call the class method initialize for each class that defines one, in class definition order.
  2. main_program calls the class method main of its parameter class.
  3. main_program, end_program, and fatal_error call the class method terminate for each class that defines one, in reverse class definition order.
  4. call_method and call_super call the instance or class method undefined_method (if the target class or superclass defines one) when an attempt is made to call a method that the target class or superclass does not define.
  5. serialize may call the serialize instance method.
  6. deserialize may call the deserialize instance method.

The instance method undefined_method and the class methods initialize, terminate, and undefined_method may only be called automatically, it an error to attempt to call them via call_method. The class method main may be called via call_method. (This might be useful to restart a program.) Calling the methods from overriding subclass methods via call_super is permissible.

The instance methods serialize and deserialize may not be called via call_method or call_super. See Serialization for details about these methods.

Method Euphoria ignores the return values of main, initialize, terminate, serialize, and deserialize.

 

EVENTS

Events represent specialized behavior of an entity. Each event may have one or more handlers assigned during the run of the program. (If an event is raised before any handlers have been assigned, nothing happens.)

When an event x is defined by a class, an instance property also named x is defined, as are three instance methods: get_x, which returns the sequence of event handlers; set_x, which sets the event handlers for the event; and a method also named x which is used to raise the event.

Event handlers are instances of the Method_Wrapper class. A method wrapper indirectly calls the method it was linked to when it was created. (Similar to a function pointer in C or a delegate in C#.)

When the event is raised by calling method x, each handler is called in the order in which they appear in the sequence of handlers. Each handler will be passed the target instance of the event, the name of the event, and all parameters that were passed to x. If a handler returns a value other than NOTHING or throws an exception, subsequent handlers are not called.

 

INTERFACES

Interfaces are special classes containing lists of instance and class methods. A class which defines each instance and class method of an interface (directly or by inheritance) as a public method is said to implement that interface. (Method Euphoria does not recognize this automatically, it must be declared in the class function defining the class.) Interfaces express relationships not based on inheritance. For example, in a role playing game program, characters, weapons, gold pieces, magic items, etc. do not have inheritance relationships with each other, but all might implement an interface which lists the method neededs to save the game state to disk and to restore it from disk. It is possible to define an interface with no methods to act as a tag. The standard library Containers package defines several tag interfaces.

Interfaces are defined using interface. In contrast to normal classes and exceptions, interfaces allow multiple inheritence: an interface may have one or more superclasses.

 

EXCEPTIONS AND EXCEPTION HANDLING

Exceptions are provided for the handling of recoverable errors and other exceptional conditions. The procedure fatal_error should be used to display error messages for non-recoverable errors.

Method Euphoria uses a crash routine which calls fatal_error to do proper cleanup.

Exceptions are special classes which form a hierarchy. The exception Exception is predefined in Method Euphoria and has no superclass. Method Euphoria also predefines several other exceptions. Exceptions are defined using exception and must specify a superclass.

When your program encounters an error, use throw to signal an exception. That exception becomes the pending exception if no other exception is pending. If another exception is pending, the program terminates: only one exception may be pending at a time. If a method is called while an exception is pending, the pending exception is saved and is not pending during the execution of that method. When the method returns, the saved exception once again becomes pending.

If a method returns while an exception is pending, the exception remains pending. If the calling method has a saved exception, this results in program termination as if an exception had been thrown while another is pending.

For the purpose of exception handling, serialize and deserialize are treated as methods.

Several functions allow you to test for an exception without processing it: success returns TRUE if no exception is pending and FALSE if there is a pending exception; failure returns TRUE if an exception is pending and FALSE if there is not; pending returns the pending exception if there is one and returns NOTHING if there is not.

To process an exception use catch. This function determines whether an exception is pending: if not, it returns FALSE. If an exception is pending, catch determines if the exception given as its parameter is the same exception as the pending exception or is a superclass of the pending exception. If so catch returns TRUE and clears the pending exception, otherwise it returns FALSE. Therefore catch(Exception) will catch any exception, as Exception is a superclass of all exceptions.

When you catch an exception and need to know the exact exception, use caught: this returns the last exception processed by catch, but returns NOTHING if there is none. If after catching an exception you want to throw the same exception again, the procedure rethrow is used. This makes the last caught exception the pending exception again. If rethrow is used when no exception has been caught, nothing happens.

 

VALIDATION

Method Euphoria provides an alternative to standard Euphoria type checking, in which a type check failure can throw an exception rather than abort the program immediately. This is used primarily for type checking method parameters. Validation also handles optional parameters.

Method Euphoria predefines special type checking functions for boolean, integer, atom, object, sequence, string and identifier. Sequence and object fail if the parameter is an entity.

Two types are predefined for use in dynamic type checking: type_specifier and anything. Type_specifer allows a type to be passed as parameter. An example is in the Container class. A type specifier is passed as a parameter to Container's constructor to specify the allowable type for elements of the container. Anything is a type that does no type checking.

A generic entity type is predefined, as are instance and class.

These types are used by the validate procedure. This procedure type checks its parameter and throws the Type_Check_Failure exception if the type check fails. The call_method and call_super functions pass the special value NOTHING if an expected method parameter is not provided. If the parameter is optional, validate will not throw an exception in this case; if it is required, it will throw the Missing_Parameter exception.

You may define additional type checks to be used in validation by using the register_type procedure.

 

SERIALIZATION

Instances can be converted into coded byte sequences. These sequences can be stored to a file, or transmitted over a network or the internet. Use serialize to create the coded sequence and use deserialize to recreate the instance. Instances can be shared by the same program running on different machines or by different programs on the same or different machines if both programs define the instance’s class and the classes of any of the instance’s property values which are themselves entities.

For most classes, serialize and deserialize will be sufficient. If custom serialization is required, define a serialize instance method taking no parameters. Your serialize method can assign property values to be serialized by using set_property with serialized as its target. To prevent the serialization of an instance but allow the serialization of any instance it is contained in to continue, use cancel_serialize: this causes the serialization of NOTHING rather than the instance. To abort the entire serialization process, throw an exception.

If custom deserialization is required, define a deserialize instance method taking no parameters. Your deserialize method can use this to read or change the property values of the deserialized instance. To prevent the deserialization of an instance but allow the deserialization of any instance it is contained in to continue, call the delete instance method with this as its target: this returns NOTHING rather than the instance. To abort the entire deserialization process, throw an exception.

Euphoria integers, atoms, and sequences can also be serialized. Classes can be serialized: when a class is serialized, its property values are not serialized.

 

CLASS DESIGN IN METHOD EUPHORIA

A class or several related classes can be defined in an include file or in the program file.

Consider the properties, methods, and events your class needs. Determine if an existing class can be used as a superclass and provide some or most of the properties, methods, and events by inheritance. Consider what interfaces should be implemented and if necessary, define new ones.

Give careful thought to the creation, copying, and destruction of the class's instances.

Consider error handling and which exceptions will be used, defining new ones if necessary.

Open the class definition by using class. The class handle returned by class should normally be assigned to a global constant; however a local constant could be used if it is desired to have the class usable only in the file which defines it.

Register each property by using property.

If a class property is intended as a constant, use a public getter method and no setter method. If the value of the constant will be the same in this class and all of its subclasses, just set the default value to the constant value, or set the value in the class' initialize class method. If subclasses will have different constant values for this property, have the subclass’ initialize method pass the value passed to the class’ initialize method as a parameter. Null methods are a good alternative, see below.

Code methods as functions or procedures taking the appropriate number of object parameters (which may be none). If the method overrides a superclass method, the superclass method may be called by using call_super if the superclass method is not private.

Register each method using method. Most methods will be public. Methods used for internal use only will be private. Methods not generally available but needed by subclasses will be protected.

Register events with event.

The null_method procedure is used to define a method which does nothing and returns a specified value. This might be useful if your class must have a method to implement an interface method but don't really need the method. It is also a simple way to define a method which returns a constant.

The super_method procedure is used to override superclass methods: it defines a method that simply passes its parameters to the overridden superclass method and returns the superclass method's return value.

Code the constructor as a class method named new which returns a newly-created instance or throws an exception and returns NOTHING in case of failure. The superclass constructor must be called (by using call_super). Normally, you will specify public access for the constructor but may use protected access to control the creation of instances of the class. If no initialization needs to be done, super_method may be used for the class' new method. Note that if the class is an immediate subclass of Entity, you must override Entity's new class method to provide public access.

If copying of instances is to be done, using the clone instance method inherited from Entity will be sufficient if a shallow copy (if the value of a property is an instance, only the handle is copied) is acceptable. Note that if the class is an immediate subclass of Entity, you must override Entity's clone instance method to provide public access. If a deep copy (if the value of a property is an instance, a copy of that instance is made) is needed, or any kind of error checking or conditional copying is to be done, define the copy constructor as an instance method named clone which returns a copied instance or throws an exception and returns NOTHING in case of failure. The superclass copy constructor must be called (by using call_super).

A destructor is often not necessary: the delete method inherited from Entity will very often be sufficient. Note that if the class is an immediate subclass of Entity, you must override Entity's delete instance method to provide public access. A destructor is necessary if instances contain system resources such as file or window handles: the destructor must release these. A destructor may be necessary if the instance can contain other instances. It may be desirable to ensure that these are destroyed when the containing instance is destroyed. In general, a reference to an external instance should not be deleted, while an instance created for internal use should be. If a destructor is needed, code it as an instance method named delete which returns NOTHING or throws an exception and returns the target instance in case of failure. The superclass destructor must be called (by using call_super).

If the class requires initialization, code a class method named initialize. This will be called automatically by main_program or start_program.

If a class requires cleanup after the normal run of the program or in case of a fatal error, code a class method terminate. This will be called when the program ends, if main_program or start_program has been executed. Note that terminate will always be called in this case, even if a fatal error occurs during the class' initialize method.

Do not call a method's implementing routine directly rather than than through call_method. This would defeat Method Euphoria’s access control and stack trace facilities. (Code Warriors can ignore this if they are careful--for example to emulate friend classes or to squeeze maximum performance out of private methods.)

 

THE APPLICATION CLASS

The application class is the class whose main class method is called by main_program. Typically, this will be the last class defined before main_program is called. It will inherit directly from Entity and will have no properties or instance methods. In some cases, the only method will be main. If there is a lot of initialization to be done, the initialize class method is a good place for it—when the application class is the last class to be defined, its initialize method will automatically run immediately before main. If a lot of cleanup is required, this can go in its terminate class method. Again assuming the application class is the last class defined, its terminate method will automatically run immediately after main. Methods to act as event handlers can also be defined in the application class, then wrapped and assigned to the correct instances in the initialize method.

When only a simple application class is needed, Method Euphoria can create it for you. Use start_program in the place of main_program, then code your main program logic. Follow your main program logic with end_program to do cleanup and terminate your program. Internally Method Euphoria will treat all code between start_program and end_program as if it were included in the class ME_Kernel.Program's main class method and Me_Kernel.Program were the application class.

Thanks to Andy Serpa for the start_program/end_program idea.

 

STANDARD CLASS LIBRARY

Method Euphoria has a small but useful class library which is contained in the following include files:

  1. me_containers.e: Containers such as stacks, queues, and self-sorting containers. Also provides for the easy creation of new container classes.
  2. me_counted.e: Instance counted classes, including the Singleton class.
  3. me_file_errors.e: Exceptions relating to file handling.
  4. me_math_errors.e: Exceptions relating to mathematical operations.
  5. me_misc_errors.e: Other useful exceptions
  6. me_variables.e: Reference variables and constants, with events.
  7. me_widgets.e: Visual Basic style collections and components for building widgets.

Version numbering of the Standard Class Library conforms to Method Euphoria. All include files in the Library will have the same version number as the current version of Method Euphoria.

Each of the include files above defines a subpackage of the ME_Std_Lib package. The method_euphoria.e file defines Entity, Interface, Exception, Method_Wrapper, and several exceptions in the package ME_Kernel. For convenience, these are documented as part of the Standard Class Library as well. The file me_std_lib.e can be used to include the entire library.

The Standard Class Library documentation can be found here.

 

DEMO PROGRAMS

Five demo programs are included:

  1. demo.ex demonstrates some of the containers in the Standard Class Library.
  2. event.ex illustrates some abstract event handling.
  3. globals.ex is a working utility that extracts and sorts all the global symbols from a Euphoria code file.
  4. savetest.ex demonstrates saving and restoring entities using a text file.
  5. speedtst.ex provides some benchmarks--adapted from Rod Jackson's speed test for Quartz.
  6. tasking.ex demonstrates Method Euphoria's implmentation of task switching.

 

COMPATIBILITY

Method Euphoria 3.0.0 is fully backward compatible with Method Euphoria 2.0.1.

Method Euphoria 2.0.1 is fully backward compatible with Method Euphoria 2.0.0 with the exception that any code relying on the repaired bugs will break.

Method Euphoria 2.0.0 is largely backward compatible with Method Euphoria 1.4.0 and later versions, but several features have been redesigned and may introduce incompatibilities.

Significant changes have been made to the runtime routines: most errors throw exceptions rather than causing fatal errors. (For example, attempting to call an unrelated class's private method will cause Access_Denied to be thrown.) This may cause bugs in programs which rely on these errors being fatal.

The serialization feature has been completely redesigned. Serialized data from previous versions can be read, but custom serialization methods must be rewritten.

The internal representation of entity handles has been changed. Programs which rely on the internal representation of entity handles will need to be rewritten.

Method Euphoria 1.4.0 changed the exception model: in previous versions it was illegal to call a method while an exception was pending. This provides the programmer with greater flexibility, but may cause bugs in programs that rely on a crash occuring if a method is called with a pending exception. Apart from this, version 1.4.0 is fully backward compatible with previous versions.

Method Euphoria is fully compatible with all Euphoria 2.5 standard include files. Though much of the code base of Method Euphoria is derived from Diamond, Method Euphoria is not compatible with Diamond.

Method Euphoria makes use of Euphoria 2.5's crash_routine, consequently it will not run on earlier versions.

Method Euphoria is not compatible with the Euphoria 2.5 Tasking Interpreter. A compatible Method Euphoria will be provided for the Euphoria 3.0 alpha release.

 

END USER LICENSE AGREEMENT

Method Euphoria consists of all files contained in method_euphoria.zip. Method Euphoria is freeware. Method Euphoria is released for private, public, and commercial use subject to these conditions:

  1. All distributions of Method Euphoria, modifications of Method Euphoria, or programs incorporating Method Euphoria shall include this End User License Agreement, the Disclaimer, and proper authorship credit.
  2. All distributions of Method Euphoria, modifications of Method Euphoria, or programs incorporating Method Euphoria shall be free of charge; but you may charge a sufficient sum to recover the cost of the distribution media.
  3. You may freely modify Method Euphoria, but all distributions of modifications of Method Euphoria must contain notice that you have made modifications and the general nature of these modifications.
  4. You may incorporate Method Euphoria, either as-is or modified, into a larger program. You may distribute your program if you comply with conditions 1, 2, and 3 (if applicable).
  5. If you wish to sell a program which incorporates Method Euphoria, whether as-is or modified, you may do so if you comply with conditions 1 and 3 (if applicable). Condition 2 is waived if and only if your program's purpose is clearly distinct from Method Euphoria's own purpose: the provision of Object Oriented Programming services for the Euphoria language. [Examples: A business application or a game incorporating Method Euphoria may be sold. A program which prints "Hello World" incorporating Method Euphoria may not--the program is clearly a ruse to evade condition 2.]
  6. You have unlimited rights to create new classes for use with Method Euphoria and to copy, distribute and sell such classes, subject to the requirement that you do use any combination of words indicating my endorsement of your classes or asserting any kind of official status of your classes anywhere in your code or documentation. This prohibiton includes but is not limited to using the package names ME_Kernel and ME_Std_Lib (including variations in case and or/spelling).
  7. Condition 6 does not apply to classes submitted to me and accepted for inclusion in official Method Euphoria libraries. Any class submitted to me and accepted will be distributed free of charge (with full authorship credit) in future releases of Method Euphoria. If you wish to sell a class, don't submit it for inclusion in an official library.

 

DISCLAIMER

Method Euphoria is released without warranty of any kind whatsoever, whether express or implied. The author is not responsible for any damages arising from the use of this software, whether direct or indirect, incidental or consequential.

USE AT YOUR OWN RISK

 

 

ALPHABETICAL LISTING OF GLOBAL ROUTINES, VARIABLES, AND CONSTANTS

 

The syntax convention for routines is to show the return value (for functions and types) and the parameters as type names with digits to distinguish them: object1, integer2, entity3, etc. All errors are listed except type clashes and illegal program contexts. Context indicates the legal program contexts for the routine; if it is omitted, all contexts are legal.

 

A B C D E F G H I J K L M N O P Q R S T U V W X Y Z

 

boolean

Variety
type
Syntax
boolean1=boolean(object1)
Description
Returns TRUE if object1 is TRUE or FALSE; otherwise returns FALSE.

 

 

call_method

Variety
function
Syntax
object1=call_method(entity1,identifier1,object2)
Context
method
Description
Calls the appropriate method of entity1's class with entity1 as its target. If entity1 is an instance, an instance method is called; if a class, class method is called. Identifier1 gives the name of the method and the parameters are contained in object2. If object2 is an atom or an entity, it is wrapped in a one-element sequence. If fewer parameters are passed than required by the method’s definition (see method), missing parameters are passed as the special value NOTHING. If there are more parameters than required, the excess parameters are discarded unless the definition specifies a parameter array: then they are passed as a single sequence. Returns the method's return value. If an attempt is made to call a method which is not defined by entity1's class, entity1's undefined_method instance or class method will be called automatically instead if one is defined. If entity1 is an instance, the instance method will be called; if a class, the class method. The name of the method which was attempted to be called is the first parameter, parameters to the attmpeted call are the second and subsequent parameters.
Note
Be careful of one parameter methods when passing a sequence. For example: call_method(x,"do_this","ABC") does not pass a single parameter "ABC" to x's do_this method--it passes three parameters 'a', 'b', and c' to x's do_this method. The correct syntax is call_method(x,"do_this",{"ABC"})
Errors

 

 

call_super

Variety
function
Syntax
object1=call_super(object2)
Context
method
Description
Calls an overridden superclass method of the currently executing method, passing object2 as the parameters as in call_method. The target of the currently executing method will be the target of the superclass method. Returns the overridden method’s return value. If the currently execting method does not override a superclass method, the superclass' undefined_method instance or class method will be called automatically instead if one is defined. If the target is an instance, the instance method will be called; if a class, the class method. The name of the method which was attempted to be called is the first parameter, parameters to the attmpeted call are the second and subsequent parameters.
Errors

 

 

cancel_serialize

Variety
procedure
Syntax
cancel_serialize()
Context
method
Description
Cancels the serialization of the current instance, but allows the serialization of any instance it is contained in to continue. If no serialization is in progress, nothing happens.

 

 

catch

Variety
function
Syntax
boolean1=catch(class1)
Context
method
Description
If class1 is the same exception as the pending exception or a superclass of the pending exception, returns TRUE and clears the pending exception; otherwise returns FALSE. Returns FALSE if no exception is pending.
Note
Since all exceptions are direct or indirect subclasses of Exception, catch(Exception) will catch any exception.

 

 

caught

Variety
function
Syntax
exception1=caught()
Context
method
Description
Returns the exact exception processed by catch if called within the method which caught the exception and no other exception has been thrown; otherwise returns NOTHING.

 

 

CLASS

Variety
constant
Description
Used in property, method, null_method, or super_method to specify a class property or method.

 

 

class

Variety
function
Syntax
class1=class(identifier1,class2,object1)
Context
initialization
Description
Begins the definition of a class with the name identifier1. Class2 is the superclass. Object1 is an interface or a sequence of interfaces (which may be empty), designating the interface or interfaces to be implemented by the class. If object1 is an empty sequence, no interfaces are implemented.
Note
It is strongly recommended to assign class1 to a global constant.
Errors
Program termination if identifier1 duplicates an existing class name in the same package, object1 is not an interface or a sequence of interfaces, or object1 contains duplicate interfaces.

 

 

class_entity

Variety
type
Syntax
boolean1=class_entity(object1)
Description
Returns TRUE if object1 is a class; returns FALSE if object1 is an instance or is not an entity.

 

 

class_name

Variety
function
Syntax
string1=class_name(object1)
Description
If object1 is a class, an instance, or a deleted entity, returns its class name. If object1 is a class name, returns the fully qualified class name. If object1 is not an entity or a class name, returns an empty string.

 

 

CURRENT_VERSION

Variety
constant
Description
The current Method Euphoria version in sequence form: {2,0,1}

 

 

debug_file

Variety
procedure
Syntax
debug_file()
Description
Creates a debug file me.err in the current directory listing:
Note
Called by fatal_error.

 

 

deleted_entity

Variety
type
Syntax
boolean1=deleted_entity(object1)
Description
Returns TRUE if object1 is an instance which has been deleted; returns FALSE if object1 is an instance which has not been deleted, a class, or is not an entity.

 

 

deserialize

Variety
function
Syntax
object1=deserialize(string1)
Context
method
Description
String1 is a coded byte string created by serialize or the name of a file created by serialize. Restores and returns the encoded object, if possible; if the deserialization fails, throws Deserialize_Error unless an exception was throw during deserialization and returns NOTHING. If the deserialization fails, any instances created by the deserialization are deleted. See Serialization for details.
Note
Only one serializtion or deserialization may be in progress at a time. Method Euphoria treats deserialize as a method call: a call to a hypothecial deserialize class method of the Entity class is placed on the program stack and will appear in error messages and the debug file.

 

 

end_class

Variety
procedure
Syntax
end_class()
Context
class definition
Description
Ends the current class definition and verifies the definition.
Errors
Program termination if the class implements an interface, and the class does not define (directly or by inheritance) a public method specified by the interface.

 

 

end_package

Variety
procedure
Syntax
end_package()
Context
initialization
Description
Ends the current package.
Errors
Program termination if no current package is defined.

 

 

end_program

Variety
procedure
Syntax
end_program()
Context
method
Description
End the program. The terminate class method is called for each class as in main_program.
Note
Intended for use with start_program, but can also be used in programs started via main_program.

 

 

entity

Variety
type
Syntax
boolean1=entity(object1)
Description
Returns TRUE if object1 is an entity (other than a deleted instance), otherwise FALSE.

 

 

error_screen_width

Variety
procedure
Syntax
error_screen_width(object1)
Description
Sets the width of the error screen for formatting of termination messages issued by fatal_error to object1. If object1 is not an integer or is less than 20 the setting is unchanged. (The initial width is 80.)

 

 

event

Variety
procedure
Syntax
event(identifier1,integer1,integer2)
Context
class definition
Description
Defines an event named identifier1 in the class currently being defined. Integer1 specifies PUBLIC, PROTECTED, or PRIVATE link access for the event; integer2 specifies PUBLIC, PROTECTED, or PRIVATE raise access for the event. For an event named x, an instance property also named x will be created to hold the list of event handlers. Two accessor methods will be created (get_x and set_x). An instance method also named x will be created to allow raising the event.
Errors
Program termination if: identifer1 duplicates an instance property name of the class or of any of its superclasses; integer1 is not PUBLIC, PROTECTED, or PRIVATE; or integer2 is not PUBLIC, PROTECTED, or PRIVATE.

 

 

exception

Variety
function
Syntax
Class1=exception(identifier1,class2)
Context
initialization
Description
Defines an exception with the name identifier1. Class2 is an exception which designates the superclass. Returns the new exception's handle.
Note
It is strongly recommended to assign class1 to a global constant.
Errors
Program termination if identifier1 duplicates an existing class name in the same package or class2 is not an exception.

 

 

extends

Variety
function
Syntax
boolean1=extends(object1,object2)
Description
Returns TRUE if object1 is a class and object2 is a superclass of object1, or if object1 and object2 are the same class; otherwise returns FALSE.

 

 

failure

Variety
function
Syntax
boolean1=failure()
Context
method
Description
Returns TRUE if an exception is currently pending, otherwise FALSE.

 

 

FALSE

Variety
constant
Description
The integer 0, used as a boolean value.

 

 

fatal_error

Variety
procedure
Syntax
fatal_error(string1)
Description
Terminates the program with an error message. Word wraps the error message based on width of the error screen; this defaults to 80, and can be set by error_screen_width. Also calls debug_file. In method context, also cause any class terminate methods to be called as in main_program; but if fatal_error is called from a class' initialize method, terminate will only be called for that class and any previously-defined classes.
The error message consists of:
Note
If fatal_error is called from a class' terminate method when the method was called automatically by fatal_error, the call is ignored.

 

 

get_class

Variety
function
Syntax
object1=get_class(object2)
Description
If object2 is an instance or a deleted entity, returns the handle of the entity's class. If object2 is a class, returns object2. If object2 is a string specifying the full name of a class or a the partial name of a class defined in the current package, returns the class entity. Otherwise, returns NOTHING.

 

 

get_property

Variety
function
Syntax
object1=get_property(entity1,identifier1)
Context
method
Description
If entity1 is an instance, returns the value of the instance property named identifier1 of the instance. If entity1 is a class, returns the value of the class property named identifier1 of the class.
Errors

 

 

identifier

Variety
type
Syntax
boolean1=identifier(object1)
Description
Returns TRUE if object1 is a string which is a valid Euphoria identifier: the first character is a letter and all of the other characters are letters, digits, and underscores; otherwise FALSE.

 

 

implements

Variety
function
Syntax
boolean1=implements(object1,object2)
Description
Returns TRUE if object1 is an class, object2 is an interface, and object1 implements that interface, directly or by inheritance; otherwise returns FALSE.

 

 

INSTANCE

Variety
constant
Description
Used in property, method, null_method, or super_method to specify an instance property or method.

 

 

instance_entity

Variety
type
Syntax
boolean1=instance_entity(object1)
Description
Returns TRUE if object1 is an instance which has not been deleted; returns FALSE if object1 is an instance which has been deleted, is a class, or is not an entity.

 

 

instance_of

Variety
function
Syntax
boolean1=instance_of(object1,object2)
Description
Returns TRUE if object1 is an instance and object2 is object1’s class or a superclass of object1’s class; otherwise returns FALSE.

 

 

interface

Variety
function
Syntax
class1=interface(identifier1,object1,object2,object3)
Context
initialization
Description
Defines an interface named identifier1. Object1 is an interface or a (possibly empty) sequence of interfaces, which are the superclasses of the new interface. If object1 is an empty sequence, Interface is the superclass. Object2 and object3 are single identifiers or (possibly empty) sequences of identifiers naming methods to be implemented by classes which implement the interface; object2 is for instance methods, object3 is for class methods.
Note
It is strongly recommended to assign class1 to a global constant.
Errors
Program termination if identifier1 duplicates an existing class name in the same package, object1 itself or any element of object1 (if it is a sequence) is not an interface, object1 contains duplicate interfaces (including an interface and one or more of its superclasses is redundant but legal), or object2 or object3 contain duplicated methods.

 

 

last

Variety
function
Syntax
entity1=last()
Context
method
Description
Returns the target of the method which called currently executing method. Returns NOTHING if the currently executing method was not called by another method.

 

 

last_class

Variety
function
Syntax
class1=last_class()
Context
method
Description
Returns the class of the target of the method which called the currently executing method. Returns NOTHING if the currently excuting method was not called by another method.
Note
Syntactic sugar for get_class(last()). Intended for instance methods; in class methods, last_class is legal but redundant, having the same value as last.

 

 

last_method

Variety
function
Syntax
string1=last_method()
Context
method
Description
Returns the name of the method which called the currently executing method. Returns an empty string if the currently excuting method was not called by another method.

 

 

main_program

Variety
procedure
Syntax
main_program(class1)
Context
initialization
Description
Terminates initialization context, does final verification of classes, begins running the program. Automatically calls the initialize class method for each class that defines one, in the order in which the classes were defined. Automatically calls the main class method of class1. Automatically calls the terminate class method of each class that defines one, in the reverse order of which the classes were defined. These method calls ignore exceptions.
Errors
Program termination if class1 does not define a main class method.

 

 

make_sequence

Variety
function
Syntax
sequence1=make_sequence(object1)
Context
method
Description
If object1 is an atom or an entity, returns a one element sequence with object1 as the element; otherwise returns object1.

 

 

method

Variety
procedure
Syntax
method(identifier1,integer1,integer2,integer3,object1)
Context
class definition
Description
Defines a method named identifier1 in the class currently being defined. Integer1 is INSTANCE or CLASS to specify an instance or class method. Integer2 specifies PUBLIC, PROTECTED, or PRIVATE access. Integer3 is the parameter count for the method. A negative parameter count may be used: this specifies a parameter array. If for example the parameter count is -4, then when the method is called with four or more parameters, all parameters after the first three are concatenated into a sequence and assigned to the method’s fourth parameter. If the method is called with three or fewer parameters, the fourth parameter will be an empty sequence. If the method is implemented as a function, object1 is the routine id of the function. If the method is implemented as a procedure, object1 is a one- or two-element sequence. The first element is the routine id of the procedure. The second element if present is the method's return value; if absent the return value is NOTHING.
Errors
Program termination if identifer1 duplicates an instance method name or class method name (as the case may be) of the class; integer1 is not INSTANCE or CLASS; integer2 is not PUBLIC, PROTECTED, or PRIVATE; the method overrides a superclass method and integer2 specifies more restrictive access than the overridden method; or object1 is not formatted as above.

 

 

NIL

Variety
constant
Description
The integer 0 used in the sense of "no meaningful data".

 

 

NONE

Variety
constant
Description
The empty sequence. A notational convenience, particularly when a sequence is intended as a list.

 

 

NOTHING

Variety
constant
Description
A special value used to represent a missing method parameter, as a return value for a method which is logically a procedure, and in certain error reporting situations, such as a failed constructor call.

 

 

null_method

Variety
procedure
Syntax
null_method(identifier1,integer1,integer2,object1)
Context
class definition
Description
Defines a null method (a method which does nothing) named identifier1 in the class currently being defined. Integer1 is INSTANCE or CLASS to specify the an instance or class method. Integer2 specifies PUBLIC, PROTECTED, or PRIVATE access. Object1 is the value which the method returns.
Note
Syntactic sugar for using method to accomplish the purpose.

 

 

OPTIONAL

Variety
constant
Description
Used in validate to indicate an optional parameter. Equal to FALSE.

 

 

package

Variety
procedure
Syntax
package(identifier1)
Contexts
initialization
Description
Defines a package named identifier1. All classes and types defined until the next end_package is encountered will be part of this package. Packages may be nested: if a package is encountered again before an end_package, this will define a subpackage.

 

 

pending

Variety
function
Syntax
exception1=pending()
Context
method
Description
Returns the exact exception currently pending; returns NOTHING if there is none.

 

 

PRIVATE

Variety
constant
Description
Used in property, method, or event to specify private access.

 

 

property

Variety
procedure
Syntax
property(identifier1,integer1,integer2,object1,object2)
Context
class definition
Description
Defines a property named identifier1 in the class currently being defined. Integer1 is INSTANCE or CLASS to specify the type of property. Integer2 may be PUBLIC or PROTECTED: this specifies that a getter method with the specified access will be automatically generated. If the property is named x, the method will be named get_x. If integer2 is PRIVATE, no getter method will be generated. Object1 may be PUBLIC, PROTECTED, or PRIVATE, as for integer2. This will generate a setter method named set_x unless object1 is PRIVATE. Object1 may also be a two or three element sequence. This will result in the generation of a setter method which performs type checking. The first element must be PUBLIC or PROTECTED to specify access. If object1 is a sequence, the second element or the second and third elements must be a valid second parameter for validate. Object2 is the initial value of the class property of the class and of its subclasses, or the initial value of the instance property for each newly-created instance of the class and of its subclasses, as the case may be.
Errors
Program termination if identifier1 duplicates an instance property name or class property name (as the case may be) of the class or of any of its superclasses; integer1 is not INSTANCE or CLASS; interger2 is not PUBLIC, PROTECTED, or PRIVATE; object1 is not formatted as above.

 

 

PROTECTED

Variety
constant
Description
Used in property, method, or event to specify protected access.

 

 

PUBLIC

Variety
constant
Description
Used in property, method, or event to specify public access.

 

 

register_type

Variety
procedure
Syntax
register_type(identifier1,integer1)
Contexts
initialization
Description
Defines a type named identifier1 for use by validate. Integer1 is the routine id of the type.
Errors
Program termination if identifier1 duplicates a type name in the same package.

 

 

REQUIRED

Variety
constant
Description
Used in validate to indicate a required parameter. Equal to TRUE.

 

 

rethrow

Variety
procedure
Syntax
rethrow()
Contexts
method
Description
Syntactic sugar for throw(caught()). Throws the last exception processed by catch, does nothing if caught would have returned NOTHING. See throw.

 

 

serialize

Variety
function
Syntax
string1=serialize(object1,object2)
Context
method
Description
Transforms object1 into a coded byte string. If object2 it is a non-empty string, it is treated as a file name. This file is created and the coded byte string will be written to it. The file name will be returned. If object2 is an empty string or is not a string, the coded byte string itself will be returned. If the serialization fails, the file (if applicable) is deleted. Throws Serialize_Error unless an exception was thrown during serialization. Returns the empty sequence. See Serialization for details.
Note
Only one serialization or deserialization may be in progress at a time. Method Euphoria treats serialize as a method call: a call to a hypothecial serialize class method of the Entity class is placed on the program stack and will appear in error messages and the debug file.

 

 

serialized

Variety
function
Syntax
object1=serialized()
Context
method
Description
If a serialization is in progress, returns a shallow copy of the instance being serialized. This can be modified without affecting the original instance. If no serialization is in progress, returns NOTHING. See Serialization for details.

 

 

set_property

Variety
procedure
Syntax
set_property(entity1,identifier1,object1)
Context
method
Description
If entity1 is an instance, sets the instance property named identifier1 of the instance. If entity1 is a class, sets the class property named identifier1 of the class. Object1 is the value to which the property is set.
Errors
  • Throws Invalid_Target if entity1 is a deleted instance.
  • Throws Undefined_Property if the property to be written is not defined by entity1's class, directly or by inheritance.
  • Throws Access_Denied if the currently executing method was not defined by the same class which defined the property.

 

 

start_program

Variety
procedure
Syntax
start_program()
Context
initialization
Description
Starts the program. The initialize class method is called for each class as in main_program, then all code until end_program is encountered is executed as if it were included in the class ME_Kernel.Program's main class method and ME_Kernel.Program were the parameter of main_program.

 

 

string

Variety
type
Syntax
boolean1=string(object1)
Description
Returns TRUE if object1 is a string; otherwise returns FALSE.

 

 

success

Variety
function
Syntax
boolean1=success()
Context
method
Description
Returns TRUE if no exception is currently pending, otherwise FALSE.

 

 

super_method

Variety
procedure
Syntax
super_method(identifier1,integer1)
Context
class definition
Description
Overrides a superclass method named identifier1 to make it public. Integer1 is INSTANCE or CLASS to specify an instance or class method.
Note
Syntactic sugar for using method to accomplish the purpose.

 

 

this

Variety
function
Syntax
entity1=this()
Context
method
Description
Returns the target of the currently executing method.

 

 

this_class

Variety
function
Syntax
class1=this_class()
Context
method
Description
Returns the class of the target of the currently executing method.
Note
Syntactic sugar for get_class(this()). Intended for instance methods; in class methods, this_class is legal but redundant, having the same value as this.

 

 

this_method

Variety
function
Syntax
identifier1=this_method()
Context
method
Description
Returns the name of the currently executing method.

 

 

throw

Variety
procedure
Syntax
throw(class1)
Contexts
method
Description
Sets the pending exception to class1, which must be an exception.
Errors
Program termination if an exception is already pending.

 

 

TRUE

Variety
constant
Description
The integer 1 used as a boolean.

 

type_specifier

Variety
type
Syntax
boolean1=type_specifier(object1)
Description
Returns TRUE if object1 is a valid second parameter for validate; otherwise returns FALSE.

 

 

validate

Variety
procedure
Syntax
validate(object1,string1,boolean1)
OR
validate(object1,{identifier1,class1},boolean1)
Context
method
Description
In the first syntax, checks if object1 belongs to the type designated by string1, which is the name of a registered type (see register_type). If the type check is successful, returns. If the type check fails, throws Type_Check_Failure. If string1 is neither the full name of a type nor the partial name of a type defined in the current package (the package in which the class which defined the currently executing method was defined), throws Invalid_Type.

In the second syntax, identifier1 must be “entity”, “instance” or “class”. If object1 is not an entity of the variety specifed by identifier1, throws Type_Check_Failure. Returns with no exception if class1 is object1's class, is a superclass of object1’s class, or object1’s class implements (directly or by inheritance) class1 if it is an interface; otherwise throws Type_Check_Failure. If the second parameter is not formatted correctly, throws Invalid_Type.

In either syntax, if boolean1 is REQUIRED, throws Missing_Parameter if object1 is NOTHING. If boolean1 is OPTIONAL, returns with no exception if object1 is NOTHING.

 

 

VOID

Variety
variable
Description
Used to discard unwanted parameters and unwanted return values, particularly the return values of a method which is logically a procedure and has no meaningful return value. Do not use VOID for any other purpose.
Note
Do not attempt to read VOID: its value is unknown as it is used internally and is used by many methods.